.\"Copyright (c) 2011, 2012, 2013 LEVAI Daniel
.\"All rights reserved.
.\"Redistribution and use in source and binary forms, with or without
.\"modification, are permitted provided that the following conditions are met:
.\"	* Redistributions of source code must retain the above copyright
.\"	notice, this list of conditions and the following disclaimer.
.\"	* Redistributions in binary form must reproduce the above copyright
.\"	notice, this list of conditions and the following disclaimer in the
.\"	documentation and/or other materials provided with the distribution.
.\"THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
.\"ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\"WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
.\"DISCLAIMED. IN NO EVENT SHALL LEVAI Daniel BE LIABLE FOR ANY
.\"DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\"(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\"LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
.\"ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\"(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
.\"SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.Dd Jan 09, 2013
.Dt KC 1
.Os
.Sh NAME
.Nm kc
.Nd console based username and password management application
.Sh SYNOPSIS
.Nm kc
.Op Fl k Ar database file
.Op Fl r
.Op Fl p Ar password file
.Op Fl m Ar cipher mode
.Op Fl b
.Op Fl v
.Op Fl h
.Sh DESCRIPTION
The
.Nm
utility is a console based username and password management application using an encrypted XML document as its database.
.Pp
A database file can contain multiple keychains, and keychains in turn can contain multiple keys (usernames if you like) and values (passwords if you like).
.Pp
After starting
.Nm
the
.Cm help
command shows the available commands, and usage information for them. If you're in a hurry, for starters, you create a new entry with the
.Cm new
command, then entering only a number in the command line will display the entry with the given index. You quit from the display with 'q' or EOT (usually CTRL+d).
.Pp
The CLI supports tab-completion for commands and keychains.
.Pp
There is a utility in the source package that converts an exported pwsafe database to a
.Nm
compatible XML database, which can be imported using the
.Cm import
command.
.Pp
.Em NOTE :
Currently there is no character set conversion taking place in the program. You either input UTF-8 and be ready to display it, or you don't input anything other than US-ASCII. You would still be able to read the database after not UTF-8 nor US-ASCII (eg.: latin2) input, but not in the way you would expect it. You can "repair" such databases, by exporting (see the
.Cm xport
command below), converting the plain text XML file to UTF-8, then importing the database. (see the
.Cm import
command below).
.Ss PARAMETERS
.Bl -tag -offset ||| -width |
.It Fl k Ar file
Use
.Ar file
as database. The default is
.Pa ~/.kc/default .
.It Fl r
Open the database in read only mode.
.Nm
will not try to lock the database file, and commands which could modify the database will not be available.
.It Fl p Ar file
Read password from
.Ar file .
.It Fl m Ar mode
Cipher mode to use.
.Ar mode
can be one of 'cbc' (the default), 'cfb128' or 'ofb'. More information is in the
.Em CIPHERS
section.
.It Fl b
Batch mode. Disable some features to enable commands from standard input.
.It Fl v
Display version.
.It Fl h
Display help.
.El
.Ss COMMANDS
These commands are available in the CLI:
.Bl -tag -offset ||| -width |
.It Cm new Op name
Create a new key with a value in the current keychain. Both key and value will be prompted for, except when
.Ar name
is specified; then it will be used as the key's name.
.Pp
Character sequences can be used in values:
.Pp
"\en" - create a new line, and make the result a multi-line value.
.Pp
"\er", "\eR" - these will be replaced with 2 and 4 (respectively) random printable characters.
.Pp
"\ea", "\eA" - these will be replaced with 2 and 4 (respectively) random alpha-numeric characters.
.Pp
Every character sequence can be used in values regardless of its order or count, and can be escaped using double backslashes (eg.: "\e\ea").
.It Cm list Op keychain
List the keys in the current keychain or if specified, in the keychain named
.Ar keychain .
Every key gets prefixed by its index number.
.Ar keychain
can be an index number or the keychain's name.
.It Cm ls Op keychain
Alias of
.Cm list .
.It Cm edit Ar index
Edit a key in the current keychain.
.Ar index
is the key's index number in the current keychain.
.Pp
Character sequence rules in values apply to this command also. See command
.Cm new
for more information about this.
.It Cm search Ar string
Search for
.Ar string
in key names in the current keychain.
If the
.Cm search
command is prefixed by a '*' (eg.: *search) then search in every keychain in the current database.
.It Cm s Ar string
Alias of
.Cm search .
.It Cm *search Ar string
Search for
.Ar string
in key names in every keychain.
.It Cm *s Ar string
Alias of
.Cm *search .
.It Cm / Ar pattern
Search for
.Ar pattern
regular expression in key names in the current keychain.
If the
.Cm /
command is prefixed by a '*' (eg.: */) then search in every keychain in the current database.
.It Cm */ Ar pattern
Search for
.Ar pattern
regular expression in key names in every keychain.
.It Cm csearch Ar string
Search for
.Ar string
in keychain names in the current database.
.It Cm c/ Ar pattern
Search for
.Ar pattern
regular expression in keychain names in the current database.
.It Cm c Ar keychain
Change the current keychain.
.Ar keychain
can be an index number or the keychain's name.
.It Cm cdel Ar keychain
Delete a keychain.
.Ar keychain
can be an index number or the keychain's name.
.It Cm clear Op count
Emulate a screen clearing. Scrolls 50 lines by default, which can be multiplied by
.Ar count
times if specified.
.It Cm clist
List keychains in the current database. Every keychain gets prefixed by its index number.
.It Cm cls
Alias of
.Cm clist .
.It Cm cnew Op name
Create a new keychain. If
.Ar name
is not given then prompt for one. Empty string cancels the addition.
.It Cm copy Ar index Ar keychain
Copy a key in the current keychain to another keychain.
.Ar index
is the key's index to copy and
.Ar keychain
is the destination keychain's index number or name.
.It Cm cp Ar index Ar keychain
Alias of
.Cm copy .
.It Cm move Ar index Ar keychain
Move a key in the current keychain to another keychain.
.Ar index
is the key's index to move and
.Ar keychain
is the destination keychain's index number or name.
.It Cm mv Ar index Ar keychain
Alias of
.Cm move .
.It Cm cren Ar keychain
Rename a keychain.
.Ar keychain
can be an index number or the keychain's name.
.It Cm del Ar index
Delete a key from the current keychain.
.Ar index
is the key's index number in the current keychain.
.It Cm rm Ar index
Alias of
.Cm del .
.It Cm passwd
Change the current database's password. All changes will be written immediately.
.It Cm help Op command
Print application help or describe a
.Ar command .
.It Cm xport Ar filename
Export the current database as an XML file named
.Ar filename .
(see command
.Cm import )
.Em NOTE :
the created XML file will be plain text, and any existing files named
.Ar filename
will be overwritten.
.It Cm import Ar filename
Import a database from the XML file named
.Ar filename .
It must be a properly formatted
.Nm
XML database. (see command
.Cm xport )
.Em NOTE :
The current database will be overwritten if saved.
.It Cm quit
Quit the program. If the database has been modified, then ask if it should be saved.
.It Cm exit
Alias of
.Cm quit .
.It Cm random Op length
Print a random string with
.Ar length
length. The default
.Ar length
is 8.
.It Cm version
Display the program version.
.It Cm write
Save the current database.
.It Cm save
Alias of
.Cm write .
.El
.Ss CIPHERS
All ciphers use 128 bit keys, generated with a KDF (key-derivation function) from the supplied password, an IV (initialization vector) and a salt. Both the IV and the salt are 128 bits long and read from the host's specific random device (
.Pa /dev/urandom
on Linux and
.Pa /dev/random
on everything else ).
.Sh EXAMPLES
.Bl -tag -offset ||| -width |
.It Cm pwsafe_convert.pl :
.Bd -literal -offset |||
# Export the pwsafe database to a cleartext file:
$ pwsafe --exportdb > pwsafe_export
Enter passphrase for .pwsafe.dat:

# Convert the cleartext pwsafe database to a kc XML database file:
$ pwsafe_convert.pl pwsafe_export kc_db.xml
opening pwsafe_export for reading.
opening kc_db.xml for writing.
Converting...
Done.
.Ed
.Pp
After the above commands, you should end up with a
.Nm
compatible XML database. You can import it to
.Nm
using the
.Cm import
command.
.It Cm Adding new entries :
.Bd -literal -offset |||
.Em Simple :
default% > new testuser
default% NEW value> testpass

.Em Prompt for both key and value :
default% > new
default% NEW key> testuser2
default% NEW value> test_\er_pass_with_random_characters:\eA

.Em Using the 'key' only as an indication :
default% > new www.mysecuresite.com
default% NEW value> user_name\enpass-word

.Em Using the random and newline character sequences :
default% > new testuser3
default% NEW value> \er\eR\en\ea\eA\enthis is a multiline value!

.Em Creating new keychains :
default% > cnew email_accounts
default% > cnew
default% NEW keychain> WebSite Accounts

.Em Results :

.Em Listing the current keychain :
default% > list
0. testuser
1. testuser2
2. www.mysecuresite.com
3. testuser3

.Em Listing any keychain :
default% > list email_accounts
empty keychain.
default% > list 2    (<-- this is the "WebSite Accounts" keychain)
empty keychain.

.Em Displaying values in the current keychain :
default% > 0
[testuser] testpass
default% > 1
[testuser2] test_,x_pass_with_random_characters:6nzm
default% > 2
[www.mysecuresite.com] [1/2] user_name
[www.mysecuresite.com] [2/2] pass-word
default% > 3
[testuser3] [1/3] v#)z!9
[testuser3] [2/3] HwRz7i
[testuser3] [3/3] this is a multiline value!

.Em Listing keychains :
default% > clist
0. default
1. email_accounts
2. WebSite Accounts

.Em Switching to other keychains :
default% > c email_accounts
email_accounts% > c 2
WebSite Accounts% >
.Ed
.It Cm Editing existing entries :
.Bd -literal -offset |||
default% > list
0. testuser
1. testuser2
2. www.mysecuresite.com
3. testuser3

.Em Edit an entry in the current keychain :
default% > edit 1
default% EDIT key> testuser2
default% EDIT value> test_pass_with_random_characters:6nzm
default% > 1
[testuser2] test_pass_with_random_characters:6nzm

.Em Rename a keychain :
default% > cren default
default% RENAME keychain> my_own keychain
my_own keychain% > 
.Ed
.El
.Sh CAVEATS
If you use 'cfb128' or 'ofb' for cipher, there is no specific sign if you enter a wrong password during the opening of a database; in this case the database would seem to be corrupt after decrypting, and
.Nm
will not be able to open it.
.Pp
There is no character conversion taking place for the input fields.
.Sh AUTHOR
.Nm
was written by
.An Daniel LEVAI
<leva@ecentrum.hu>
.Pp
Source, information, bugs:
http://keychain.googlecode.com
